Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NXFormatter

Inherits From:	Object

Declared In:	eointerface/NXFormatter.h

Class Description

An NXTableView uses NXFormatter objects to display and edit individual fields. Though a formatter only displays or edits one value at a time, but because the format within a table view's row or column is uniform, the formatter is usually associated with an entire row or column. Because a formatter can be reused for many different fields, it has to get the values to display from a data source that can provide values based on position within an axis.

Note:  An NXFormatter's data source is an object that implements methods of the NXTableDataSource informal protocol, and is not the sort defined by the EODataSources protocol. In fact, for an NXTableView used with an EOController the data source is an EOColumnAssociation.

NXFormatter is an abstract superclass. The Enterprise Objects Framework provides three concrete subclasses for displaying text and images:

·	NXImageFormatter, which scales and displays images
·	NXTextFormatter, which quickly displays static (uneditable) text
·	NXEditableFormatter, which displays editable text

NXFormatter's primary method is drawFieldAt::inside:inView:withAttributes::usePositions::. This method, invoked by an NXTableView to display a value, defines the way in which an NXFormatter formats and displays that value. The default implementation of this method does nothing; each subclass must implement it in a meaningful way.

Batching

NXFormatter defines three methods for optimization of repeated display of values. This allows a formatter to set up and reuse some initial state (such as font or PostScript graphics state) that would be expensive to reestablish for each individual field. beginBatching: tells the formatter to set up its state, resetBatching: tells it to reset that state, and endBatching tells the formatter that the repeated display is over and that it can dispose of the cached state.

Notifying the Formatter's Delegate

An NXFormatter capable of editing its values notifies its delegate of changes by sending messages described in the NXFormatterValidation informal protocol specification. All a delegate need to receive notification is implement the appropriate method; if the delegate doesn't respond to a message it isn't sent.

Instance Variables

id delegate;

id dataSource;

id value;

delegate	The formatter's delegate.

dataSource	The object that provides the formatter with values to display; this is also the data source of the formatter's axis.

value	The value to be formatted (an object conforming to the NXTableValue protocol).

Method Types

Getting and displaying a value 	- getValueAt::withAttributes::usePositions::
- drawFieldAt::inside:inView:withAttributes::
usePositions::

Batching format requests	- beginBatching:
- resetBatching:
- endBatching

Assigning a delegate	- setDelegate:
- delegate

Assigning a data source	- setDataSource:
- dataSource

Instance Methods

beginBatching:

- beginBatching:(id <NXTableVectors>)attributes

Informs the NXFormatter that a formatting session is about to begin. You never invoke this method directly; it's invoked automatically by the NXTableView just before it sends the first in a series of drawFieldAt::... messages. A formatting session is concluded by an endBatching message and is restarted by resetBatching:.

The default implementation of beginBatching: does nothing. You can reimplement this method in a subclass to perform pre-formatting initialization to optimize a series of display operations. The return value is ignored. The attributes argument is currently unused (it's always nil).

dataSource

- dataSource

Returns the NXFormatter's data source.

See also:  - dataSource (NXTableView)

delegate

- delegate

Returns the NXFormatter's delegate.

drawFieldAt::inside:inView:withAttributes::usePositions::

- drawFieldAt:(unsigned int)rowIndex
:(unsigned int)columnIndex
inside:(NXRect *)frameRect 
inView:aView
withAttributes:(id <NXTableVectors>)rowAttributes 
:(id <NXTableVectors>)columnAttributes
usePositions:(BOOL)rowPosFlag
:(BOOL)columnPosFlag

Retrieves a value from the data source, formats it, and displays it in aView. NXFormatter's implementation does nothing and returns self; it's up to a subclass to implement this method in a meaningful way.

Typically, a subclass's implementation follows these steps:

1.	Retrieve the value to display. This is done by using getValueAt::... with the arguments, which sets the NXFormatter's value instance variable:

[self getValueAt:rowIndex :columnIndex
      withAttributes:rowAttributes :columnAttributes
      usePositions:rowPosFlag :columnPosFlag];

2.	The formatter prepares value for display, for example, by creating a Cell to do the drawing. The formatter can use rowAttributes and columnAttributes to determine alignment and other display properties.

3.	The formatter displays the formatted value inside frameRect, which is given in aView's coordinate system. Note that the focus will be locked on aView before this message is sentÐthe formatter doesn't have to lock the focus itself.

Note:  aView isn't an NXTableView, but a private view used by the NXTableView.

endBatching

- endBatching

Notifies the NXFormatter that a formatting session is over. See the beginBatching: method for more information. The return value is ignored.

See also:  - resetBatching:

getValueAt::withAttributes::usePositions::

- getValueAt:(unsigned int)rowIndex
:(unsigned int)columnIndex
withAttributes:(id <NXTableVectors>)rowAttributes
:(id <NXTableVectors>)columnAttributes
usePositions:(BOOL)rowPosFlag
:(BOOL)columnPosFlag

Retrieves a value from the data source, places it in the NXFormatter's value instance variable, and returns the value. You never invoke this method from your application; however, if you create a subclass of NXFormatter, it needs to invoke this method from the implementation of drawFieldAt::..., as explained in the description of that method. A subclass of NXFormatter doesn't normally need to override this method.

The ªuse positionº flags determine which retrieval methods of the data source are used. If both are NO, then getValueFor::into: is sent to the data source with the identifiers of rowAttributes and columnAttributes. If one of the flags is YES, then getValueFor:at:into: is sent to the data source with the corresponding index argument and the identifier of its complementary axis. For example, if rowPosFlag is YES, this message is generated:

[dataSource getValueFor:[columnAttributes identifier] at:rowIndex
    into:value];

The result is undefined if both flags are YES.

See also:  - identifier (NXTableVectors protocol)

resetBatching:

- resetBatching:(id <NXTableVectors>)attributes

Tells the NXFormatter to restart a formatting session. See the beginBatching: method for more information. The return value is ignored.

See also:  - endBatching

setDataSource:

- setDataSource:anObject

Sets the NXFormatter's data source to anObject. Returns self.

See also:  - setDataSource: (NXTableView)

setDelegate:

- setDelegate:anObject

Sets the NXFormatter's delegate to anObject. Returns self.